<HTML><HEAD><TITLE>compile(++Source, ++Options)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Predicate Database and Compiler</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>compile(++Source, ++Options)</H1>
Compile specified file, or list of files, with given options
<DL>
<DT><EM>Source</EM></DT>
<DD>Source file name (atom or string) or structure stream(Stream)
</DD>
<DT><EM>Options</EM></DT>
<DD>List of compiler options
</DD>
</DL>
<H2>Description</H2>

   Compiles the specified ECLiPSE source file or list of source files,
   with the given options.  See below for a detailed description of the
   options.
<P>
<h3>Source Location</h3>
   The atom or string File must be instantiated to a legitimate
   specification for an existing file except for the suffix.
   The predicate tries to add to it the source suffixes from the list
   specified in the global flag prolog_suffix, and look for an existing and
   readable file.  As soon as a file is found which exists, it is taken as
   the input file name.  The default source suffixes are empty suffix,
   .ecl and .pl.
<P>
   If File is of the form library(Name), the predicates looks for the file
   in the directories from the library_path flag.
<P>
   If File is the special atom 'user', the source will be taken from
   the current 'input' stream, i.e. will usually generate a prompt
   at which clauses can be typed in.  In this case, input must be
   terminated either by typing CTRL-D (on Unix), CTRL-Z + RETURN
   (on Windows), or with the single atom end_of_file, followed by
   a fullstop/period.
<P>
   If File is the special form stream(Stream), then the source is taken
   from the given stream (which must be already opened).  The stream
   content is compiled until the end of stream, but the stream is not
   closed.
<P>
   When File is not in the current directory, ECLiPSe first changes the
   current directory to that of the file.  Consequently, recursive
   compile/1 calls inside compiled files can use relative pathnames.  This
   makes it possible to compile the top program files from any directory
   and still use only local file names inside.  At the end of the compilation,
   the current directory is changed back to the initial one.  This has the
   side effect that all calls to cd/1 in queries in the compiled file are
   ignored.
<P>

<h3>Code Generation Options</h3>
<DL>
<DT>debug:</DT><DD>
    This option (off/on) determines whether the resulting code contains
    debugging information.  If off, subgoals of the compiled predicates will
    not be visible to the debugger, the code will be significantly smaller,
    and slightly faster.
    The default value is taken from the global flag debug_compile.
    The setting can be changed via a pragma (debug/nodebug) in the code.
</DD>
<DT>expand_goals:</DT><DD>
    This option (off/on, default taken from global flag goal_expansion)
    determines whether inlining (a.k.a. goals macros) is performed.
    The default value is taken from the global flag goal_expansion.
    The setting can be changed via a pragma (expand/noexpand) in the code.
    Should only be switched off if a problem with inlining is suspected,
    or to get a debugger trace that is closer to the source code.
</DD>
<DT>opt_level:</DT><DD>
    Currently the integer 0 or 1, with 1 the default. Setting this to 0
    will disable certain compiler optimizations and usually reduce performance.
</DD>
</DL>
<h3>Output Options</h3>
<DL>
<DT>load:</DT><DD>
    When loading is requested, the abstract machine code produced by the
    compiler gets assembled and loaded into memory as executable code.
    Values for the 'load' option are:
    <DL>
    </DD><DT>all (default)</DT><DD>
        Load and replace code in memory, create/re-create all modules,
        interpret pragmas, and execute all directives and queries.
    <DT>none</DT><DD>
        Do not load any code into memory, do not execute queries,
        but interpret pragmas and execute directives.
        Do not re-create modules, but create new ones and erase them
        again after compilation.
    </DD><DT>new</DT><DD>
        Do not overwrite any code in memory, but load new predicates.
        Do not execute queries, but interpret pragmas and execute directives.
        Do not re-create modules, but create new ones and erase them
        again after compilation. For existing modules, erase pragmas.
    </DD></DL>
</DD>
<DT>output:</DT><DD>
    The abstract machine code which is the result of the compilation can
    be output in various forms.  Values for 'output' option (default: none):
    <DL>
    <DT>none</DT><DD>
        no output (but code may be loaded, see load option),
    </DD><DT>asm</DT><DD>
        output compiled code in asm format to input file with .asm suffix.
        This format represents the code as WAM code that can be loaded back
        into ECLiPSe using the assembler (lib(asm)).  
    </DD><DT>asm(File)</DT><DD>
        output compiled code in asm format to File.
    </DD><DT>eco</DT><DD>
        output compiled code in eco format to input file with .eco suffix
        This format can be loaded using ensure_loaded/1 or the compiler
        itself.
    </DD><DT>eco(File)</DT><DD>
        output compiled code in eco format,
    </DD><DT>print</DT><DD>
        print resulting WAM code to the output stream,
    </DD><DT>print(Stream)</DT><DD>
        print WAM code to Stream,
    </DD><DT>listing</DT><DD>
        print WAM code to input file with .lst suffix,
    </DD><DT>listing(File)</DT><DD>
        print WAM code to File,
    </DD></DL>
</DD>
<DT>outdir:</DT><DD>
    Value is the destination directory for all output files.
    The default is the empty string "", meaning that all output files
    go into the same directory as the corresponding input file.
</DD>
</DL>
<h3>Information Options</h3>
<DL>
<DT>verbose:</DT><DD>
    This option controls whether the compiler produces any log messages to
    the log_output stream. The value is a positive integer. Level 0 is the
    most silent, 1 is quiet, 2 is verbose.  Level 1 produces a log of all
    compiled predicates. Default: 0.
</DD>
<DT>warnings:</DT><DD>
    Controls (on/off) whether warnings are printed during compilation.
    Default: on.
</DD>
</DL>
<h3>Expert Options</h3>
<DL>
<DT>expand_clauses:</DT><DD>
    This option (off/on, default:on) determines whether clause macros, such
    as DCGs and delay clauses are being expanded.  Should not be switched off.
</DD>
<DT>print_normalised:</DT><DD>
    Print result of the normalisation pass (on/off, default:off).
</DD>
<DT>print_indexes:</DT><DD>
    Print result of indexing  analysis (on/off, default:off).
</DD>
<DT>print_lifetimes:</DT><DD>
    Print result of the variable lifetime analysis (on/off, default:off).
</DD>
<DT>print_raw_code:</DT><DD>
    Print annotated WAM code before register allocation (on/off, default:off).
</DD>
<DT>print_final_code:</DT><DD>
    Print annotated WAM code after register allocation (on/off, default:off).
</DD>
<DT>skip:</DT><DD>
    This option (off/on, default:off) determines whether all compiled
    predicates have their 'skip' flag set by default.  This means that
    subgoals of these predicates will be hidden in the debugger trace,
    unless the flag is reset at runtime.
</DD>
<DT>srcroot:</DT><DD>
    This is used to make the compilation result (e.g. .eco files) independent
    of absolute source file names: when the option is set to a non-empty string,
    wich is a parent directory of a source file, the source file property of the
    compiled predicates will be set as a pathname relative to the given
    root directory.
</DD>
<DT>system:</DT><DD>
    This option (off/on, default:off) causes all compiled predicates to
    have their type-flag set to 'built_in'.  This is used for compiling
    system files.
</DD>
</DL>

<h3>Compiling Modules</h3>
   In the absence of module-directives (module/1,3) within the file, the
   file content is compiled into the module from which compile/2 itself
   was called.  This context module may be modified using the @/2 notation,
   i.e. compile(File,Options)@Module.  Existing static predicates will
   be redefined, and clauses for dynamic predicates appended to the
   existing ones (unless the 'load' option requests otherwise).
<P>
   If the compiled file contains module directives (module/1,3), these
   specify to which module(s) the compiled code belongs.  Module directives
   are effective from the point where they occur until the next module
   directive, or until the end of file.  If a module directive refers
   to a module that exists already, this module is erased and redefined
   (unless the 'load' option requests otherwise).
<P>
   For backward compatibility with older ECLiPSe versions, we allow a
   module name in place of the Options-list.  If this module does not exist,
   compile/2 will create such a module and compile the content of file
   into this module, as with compile(File)@Module.
<P>
   In addition to the exceptions listed below, any exception can occur during
   compilation, because general code may be executed in directives (:-/2), file
   queries (?-/2), macro transformations and inline expansion code.
    
<H3>Modules</H3>
This predicate is sensitive to its module context (tool predicate, see @/2).
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>Either File or Options is not instantiated.
<DT><EM>(5) type error </EM>
<DD>File is instantiated, but not to a valid source specification.
<DT><EM>(5) type error </EM>
<DD>Options is not a valid options list, nor a module name.
<DT><EM>(61) inconsistent tool redefinition </EM>
<DD>A predicate that was already defined is later declared to be a tool.
<DT><EM>(62) inconsistent procedure redefinition </EM>
<DD>Illegal attempt to change a predicate's properties like: tool, dynamic, demon, parallel, calling convention.
<DT><EM>(82) trying to access a locked module </EM>
<DD>The module in which the clauses should be compiled is locked.
<DT><EM>(94) trying to redefine an existing imported procedure </EM>
<DD>There is already am imported predicate of the same name.
<DT><EM>(130) syntax error: illegal head </EM>
<DD>The head of a clause is not an atom or a compound term.
<DT><EM>(131) syntax error: illegal goal </EM>
<DD>A subgoal in the body of a clause is not an atom, a compound term or a variable.
<DT><EM>(134) procedure clauses are not consecutive </EM>
<DD>The clauses of a procedure are not consecutive.
<DT><EM>(136) trying to redefine a built-in predicate </EM>
<DD>Attempt to redefine a built-in predicate without declaring it first.
<DT><EM>(137) trying to redefine a procedure with another type </EM>
<DD>A procedure which was previously referenced as built-in or external is now defined as a regular one, or vice versa.
<DT><EM>(139) compiled or dumped file message </EM>
<DD>This event is invoked at the end of each compiled file, by default it prints the compilation time and size of compiled code.
<DT><EM>(143) compiled query failed </EM>
<DD>A query in the compiled file has failed. This is by default ignored and the compilation continues.
<DT><EM>(145) procedure being redefined in another file </EM>
<DD>A procedure is being redefined in another file than the original one.
<DT><EM>(147) compilation aborted </EM>
<DD>This event is raised just before a compilation is aborted because of an error.
<DT><EM>(148) bad pragma </EM>
<DD>An unrecognised pragma was used in the code.
<DT><EM>(171) File does not exist :  </EM>
<DD>File does not exist.
</DL>
<H2>Examples</H2>
<PRE>
</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/compiler/compile-1.html">compile / 1</A>, <A HREF="../../kernel/compiler/compile_stream-1.html">compile_stream / 1</A>, <A HREF="../../kernel/compiler/compile_term-1.html">compile_term / 1</A>, <A HREF="../../kernel/compiler/compile_term-2.html">compile_term / 2</A>, <A HREF="../../kernel/compiler/ensure_loaded-1.html">ensure_loaded / 1</A>, <A HREF="../../kernel/compiler/lib-1.html">lib / 1</A>, <A HREF="../../kernel/modules/use_module-1.html">use_module / 1</A>, <A HREF="../../kernel/directives/pragma-1.html">pragma / 1</A>, <A HREF="../../lib/fcompile/fcompile-1.html">fcompile : fcompile / 1</A>
</BODY></HTML>
